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1.  Introduction 


With  its  compact  form  factor,  portability,  low  power  consumption,  and  increasing 
processing  power,  the  Android  mobile  platform  is  gaining  popularity  as  a 
replacement  for  traditional  desktop  or  laptop  computers  as  a  processing  platform. 
Most  digital  signal  processing  algorithms  developed  at  the  US  Army  Research 
Laboratory  are  written  in  the  C  programming  language  to  provide  sufficient 
processing  power  to  satisfy  typical  processing  and  performance  requirements. 
Typical  applications  developed  for  the  Android  mobile  platform  are  written  in 
Java.  Therefore,  to  achieve  maximum  speed,  there  is  a  need  to  bridge  Java-based 
applications  to  native  C  applications.  Fortunately,  a  combination  of  the  Android 
Native  Development  Kit  (NDK)  and  the  Java  Native  Interface  (JNI)  provides  such 
a  mechanism. 

NDK  is  a  toolset  that  allows  users  to  build  C/C++  functions  into  a  static  or 
dynamic  library  or  let  the  existing  prebuilt  library  be  called  from  an  Android 
application.  JNI  defines  a  way  for  managed  code  written  in  Java  to  interact  with 
native  C/C++. 

This  guide  is  intended  to  take  programmers  through  adding  an  NDK  package  into 
an  Android  Studio  Integrated  Development  Environment  (IDE),  to  building  a 
simple  Android  application  that  calls  a  C  function  to  add  2  integer  values  received 
from  the  user  screen. 

2.  Android  Studio  IDE 


This  guide  assumes  the  user  has  already  downloaded  the  Android  Studio  IDE  and 
has  an  extensive  working  knowledge  of  this  development  package.  As  of  the 
writing  of  this  report,  the  version  of  Android  Studio  IDE  was  1.5.1. 

3.  Android  NDK  Package 

The  Android  NDK  package  can  be  downloaded  via  either  of  the  following 
methods. 

3.1  Method  1 

The  latest  version  of  the  NDK  package  for  one’s  operating  system  can  be 
downloaded  directly  from  “developer.android.com/ndk/downloads/index.html”. 

Expand  the  package  once  it  has  downloaded. 
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3.2  Method  2 


Download  the  NDK  package  directly  from  Android  Studio  IDE: 

1)  Select  the  “Tools”  tab. 

2)  Select  “Android->SDK  manager”. 

3)  Select  “Appearance->System  Settings-> Android  SDK”. 

4)  Select  the  “SDK  Tools”  tab. 

5)  Check  the  box  labeled  “Android  NDK”. 

6)  Select  “Apply”. 

Wait  for  the  package  to  be  added  into  the  Android  Studio  IDE.  The  downloaded 
package  can  be  found  at  “~/Library/Android/sdk/ndk-bundle”. 

4.  Configure  NDK  with  Android  Studio  IDE  1.5.1 

Perform  the  following  steps  to  configure  the  NDK  with  Android  Studio  IDE, 
version  1.5.1: 

1)  Set  up  the  Android  NDK  location: 

a)  Select  “File->Project  Structure”. 

b)  Select  “SDK  Location”. 

c)  If  Method  1  was  chosen,  enter  the  NDK  location  of  where  the 
downloaded  NDK  package  was  expanded.  If  Method  2  was  chosen, 
then  Android  Studio  will  automatically  fill  in  the  NDK  location. 

2)  Add  the  JAVAH,  NDK-BUILD,  and  NDK-BUILD  CLEAN  paths: 

JAVAH  is  a  tool  provided  by  Java  SE  to  generate  a  C  header  and  the 
source  files  that  are  needed  to  implement  native  methods.  Refer  to 
http://docs.oracle.eom/javase/7/docs/teehnotes/tools/windows/javah.html 
for  a  detailed  description. 

3)  Configure  the  JAVAH  path: 

a)  Select  “Tools->Android->SDK  Manager”. 

b)  Select  “Tools->Extemal  Tools”. 

c)  Select  “+”  at  the  bottom  of  the  right  pane. 

d)  The  “Create  Tool”  window  (Fig.  1)  will  pop  up. 
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•  •  Create  Tool 

Name:  Croup:  External  Tools 

Description 

Options 

0  Synchronize  files  after  execution  0  Open  console 

Show  console  when  standard  out  changes  Show  console  when  standard  error  changes 
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0  Main  menu  0  Editor  menu  is?  Project  views  IS?  Search  results 
Tool  semngs 
Program: 

Parameters: 

Wording  directory 


Insert  macro- 
insert  macro ... 
Insert  macro... 


Fig.  1  Create  Tool  window 

e)  Enter  the  following  to  create  a  path  for  “javah”,  as  shown  in  Fig.  2. 


«  Android  Studio  File  EcM  View  Navigate  Code  Analyze  Refactor  Build  Run  Tools  VCS  Window  Help 
•  •  _  Create  Tool 

Name  |  javah  |  Croup: 
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[v?  Show  console  when  standard  error  changes 
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0  Main  menu  0  Editor  menu  0  Project  views  0  Search  results 
Tool  settings 

Program  /  Ubwy/Java/JavaVirtualMachines/jdk  1 . 7.0_80.jdk/Contents/Home/hin/javah 


Parameters  -classpath  SCIasspathS  -v  -Jni  IFileClassS 

Working  directory:  SSourcepathEntryS/../jni| 


Insert  macro... 
Insert  macro  - 
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Cancel  i  OK  | 


Fig.  2  “Javah”  path 
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Notes: 


•  Program :  This  needs  to  point  to  where  the  JAVAH  application  is  located 
on  the  host. 

•  Parameters :  The  parameters  are  set  to  -classpath  $Classpath$  -v  -jni 
$FileClass$ 

o  -classpath  specifies  the  path  for  “javah”  to  look  for 
classes 

o  -v  verbose 

o  -jni  tells  “javah”  to  create  an  output  file  with  JNI-style 

native  method  function  prototypes 

•  Working  directory :  All  the  required  files  needed  to  create  a  C  callable 
object  are  located  in  the  “jni”  directory. 

NDK-BUILD  is  a  shell  script  used  to  call  a  GNU  “make”  3.81  or  later.  Use 
the  following  steps  to  configure  it: 

1)  Configure  the  NDK-BUILD  path: 

a)  Select  “Tools->Android->SDK  Manager”. 

b)  Select  “Tools->Extemal  Tools. 

c)  Select  “+”  at  the  bottom  of  the  right  pane. 

d)  The  “Create  Tool”  window  (see  Fig.  1)  will  pop  up. 

e)  Enter  the  following  to  create  an  environment  path  for  NDK-BUILD,  as 
shown  in  Fig.  3: 

•  Program :  This  points  to  the  location  to  where  NDK-BUILD  is 
located. 

•  Parameters'.  Leave  blank. 

•  Working  directory :  This  points  to  where  all  the  Java  files  are 
located. 
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trim  Lee  Cradh  Console 


Fig.  3  Environment  path 

NDK-BUILD  CLEAN  is  used  to  remove  all  previously  generated  binaries.  Use 
the  following  steps  to  configure  it: 

1)  Configure  the  NDK-BUILD  CLEAN  path: 

a)  Follow  the  same  steps  as  if  configuring  the  NDK-BUILD  path,  except 
the  parameter  is  set  to  “clean”. 

b)  The  final  NDK-BUILD  CLEAN  configuration  screen  should  look  like 
Fig.  4. 
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Fig.  4  NDK-BUILD  CLEAN  configuration 

5.  Create  an  Android  Application 

This  guide  assumes  that  the  user  is  well  versed  in  using  the  Android  Studio  IDE 
to  create  an  Android  application.  Therefore,  a  step-by-step  guide  on  how  to  create 
an  Android  application  has  not  been  included.  A  simple  Android  application  is 
provided  as  an  example  highlighting  the  functionality  outlined  in  this  report. 


A  newly  created  Android  application  is  shown  is  Fig.  5. 


Fig.  5  Android  application 

The  user  can  then  add  the  ability  to  read  in  2  integer  numbers,  as  shown  in  Fig.  6. 
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Fig.  6  Java  codes  to  add  2  integer  numbers 

To  do  this,  the  user  must  set  up  a  sequence  to  call  a  C  function  from  an  Android 
application: 

1)  Create  a  native  library  Java  class  as  shown  in  Fig.  7.  This  class  resides  in 
the  “sre  “directory.  This  class  includes  an  Android  system  call  to  load  the 
library  that  was  written  in  C  and  all  the  C  function  prototypes. 


*-**-►«*  EL  *  fit  i!_  Q  « 


Fig.  7  Native  library  Java  class 
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2)  Create  the  JNI  directory  as  shown  in  Fig.  8,  to  store  all  related  C  source 
files  and  H  header  files: 

a)  Select  “app->New->Folder->JNI  folder”. 

b)  Select  “Finish”.  The  “jni”  directory  should  appear  under  the  “app” 
directory. 


3  -  : 


^ 
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j  event  Lao  ■  Cradle 


*  -to  kr:  VTT-m  ...... 


Fig.  8  JNI  directory 

3)  Create  the  JNI  header  file  using  the  external  tool  JAVAH,  as  shown  in 
Fig.  9: 

a)  Select  “NativeLib->NDK->javah”: 

Based  on  the  Java  class  created  earlier,  a  header  file  will  appear  under 
the  “jni”  directory  that  has  the  following  naming  convention. 

•  PackageName:  com_example_haovu_addtwonumbers 

•  Followed  by  the  NativeJavaClassname:  NativeLib 

•  Followed  by  the  .h  extension 

•  Example:  com_example_haovu_addtwonumbers_NativeLib.h 

b)  The  newly  created  header  file  contains  the  Java  native  function 
prototypes  with  the  following  format: 

•  JNIEXPORT 

•  The  function  return  type 
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*  MefJratfJ  IM 

*  Signaiure;  fJJ.il 


jldfiT*iinriiatH>rc_ft»i  I  vat  1 1 


JNIEXPflflT  •  • .  JMULlL  Jcra^coft.eiibm tc_lbapvg_odil  two  number Sjltat  i  YeLili_adtl 
(JW6»V  | object*  Unj,  liflDj 

+  flbsst  c J;  ,wrv  i  r^iHiter Tw&n  i.Mtur  rj. Jtat  JinptlQ 

*  MprJiad.!  ii#J  Eb 

*  ffJpnptPiitr:  ( JLjOiiV  tsf^/String; 


i  Li  JNICALL  Jaya^EMyc-KaffpIe^iBVbjtfdiwonuntters^aT  ivvLi^Jial  Is 
i  J object!; 


Pirijef  . 

y 

Prnaif 


91  AddTwoNumbtrs.jp 
boiiil.grj.aie 
I ,!  «radte.  prsprrws 

in  Jb  pxih 


'  7tilbr*ryJ,Javb/ja¥irVirtuoWac!iioBiyjidlil .  7 . 4^6  ».  jdk.iContofita/lkiKAin/ javati  . . 

[Cftot  ing  file  H.eyu  Lo  rH  l.oribi  ec  t  [ohf  iiTaFple  hbovu  jddtenwiLFTibera.  NbtivoLlbjh]  ] 

J’r'bCes-S  flftlsnfed  witli  tstlf  qprlr  -ft 


”  Tsrmlmfl  i  C:  Android  Monitor  «:  Q:  Messages  _  ij;  Run  *  TOOO 
Cridlc  build  ilmtncd  m  ir  ttlMii  ImSjrrtrtW  ago! 


P'  S  ftenr  Log 
II  U--  UTf-B!  •  ■ 


Fig.  9  JNI  header  file 

c)  Under  the  “jni”  directory,  create  a  C  source  file  (NativeLibC.c),  as 
shown  in  Fig.  10,  to  implement  the  native  C  functions: 

i)  Select  “jni->New->C/C++  Source  File”. 

ii)  Enter  the  filename  and  type. 

iii)  Select  “OK”. 
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*  «  app  ► 

*  f  Nat»v*UI»_C.e 


n  .Idea 
Clapp 
►  CD  build 
n  lib* 

▼  Dire 

a-  CD  androfcfTesi 
w  r )  mam 

▼  T  i  com.eMample.haovu.addtwonu'nbcr 
MnnArrv.ty 
<  a  NabveUO 

a  C3>n< 

•  «vn.r>impl»  luovu  iddtwonunnb* 
NafiveLib_C.c 

•  NativeUb_C.h 
►  Cara* 

a»  AndrordMarufeit.xml 
►  Hi  test 


NDK  support  ii 

I 


da  c  MainAciivitvjav*  > 
n  experimental  feature  ar 


•:  hlatrveLibjav*  »  •  KatiwUti.C  h  x 

II  ute  catei  are  not  yet  supported. 


-NetiveL4b_C.lt' 


PI  app.iml 
(*?  build  .grad  le 

proguard -rules. pro 
bgradlt 

B  .gitignore 

91  AddT woNuniDm  .ml 

i?  budd-gradle 

!«•  grad  le  p  r opertie  s 


erocett  finished  vit 


■  Terminal  ■§■  (i  Android  M 

..  I  Cradle  build  llnithed  in  aeSms  <i 


Q  Messages  4  Run  I  TOGO 


Fig.  10  Create  a  C  source  file 

d)  Implement  the  Java  native  C  functions  as  shown  in  Fig.  1 1 . 


►  • 


©  +  o-  i* 


Ma*»v*lib_e.c 

•  ty  _main.it  ml 


app  v  i  *  tom_eMamela_haovu_addrttonumAert.NattveUb.Iii  v  i gradle.propertiet  > 


▼  r  AddT woN  umbers 

b  CD  grad!# 

►  CD  .idea 
▼  Ci*PP 
►  ri  bund 
nubt 
▼  Dire 

b  CD  and'odTest 


/OocumentsrMyAndroid  Dev/Adi 


▼  Qjava 

▼  G  icom.example.haovu  addtwonumber 
-  t,  Ma.rvArtiv.ty 
C  a  N.ilivrliO 

*  Djid 

I*  com.exansple.heowi.addtwonumbe 
[•  NattveUb.C.c 
[e  NanveUb_C.lt 

b  r.  res 

«•  AndroidMamfest.xmt 
b  Qtett 
□  ffAgnore 
91  app.iml 
0  build  grad  le 
0  proguard -rules,  pro 
CD  grad  le 
Q  .glt>gnore 
91  AddT woNumbert.  imi 


VjnAtt.vtv.avi  •  NadveUbpva  •  ■  NatrveUb.C, 

NDK  support  is  an  experimental  feature  and  all  use  cases  are  not  yet  supported. 

//  frrufrd  try  tun  vu  an  4/iS/Jt. 

•include  -CM_0MMple_lwtovu_addtMOnuttbers_Mativei.il>- h" 

JNIEXPCAT  )int  XICALL  Jav«_coei_e*Mple_haovu  «ddtttonunbcr*.NaUvsrt.ib„add<>lienv  -env,  ] object  obj.  jint  vail,  lint  val2H 
return  valleval2; 

> 

XIEXPOftT  : string  JNICAll  Java_co*i_cxaffpVe_haovu_addtwoniar*ers_NativeLib_heUo( JNIEnv  ««nv,  J object  objH 
return (a«nvJ-»NeM5tring<env. “Hello  ttarld'*); 


;  t  i. 

*  E 

u  t. 


app.mergeDtbugAndroidTestResources  uP-TO-OATE 
app  proressDebugAndroidTrttResourcfs  UP- TO- DATE 
app.  gene  rate  OebugAndroidTestSourees  UP-TO-DATE 
app  comprteOebuglavaWttUavac 
app  r ompdeDebugNdk  UP-TO-DATe 
appcompdeOebugSources 
app  compile OebugAnd roidTatgavaMfl tl\)a vac 
.app  comp JcOebugAnd r cudT estNd  k  UP-TO-DATE 


i 

appcompaeOebugAndroidTestSources 

♦ 

a 

M 

O  BUILD  SUCCESSFU 

I 

? 

<ur  Total  time  0.714  sees 

i 

l 

O  0  errors 

s 

O  0  warnings 

1 

See  complete  output  n  console 

|  Tnmml  .  $  Android  Monttor  Q  Messages  ►  £  Bun  *  TOGO 

‘  1  tvenl  log  Cradle  Consol* 

U 

Cradle  build  finished  in  SO  1ms  (yesterday  t  WWi 

12.4*  0:  Uir-a:  Context.  gti-armbS-vaa  - 

H 

Fig.  11  Java  native  C  functions 
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USVon  uaitn  ^  .won  PWdwy  *  **<3;  tubs*  i*M*  3 


e)  Modify  “build.gradle  (Module :app)”: 

i)  Inside  the  “defaultConfig”  section,  add  the  following  pseudo  code: 

sourceSets  { 
main{ 

jni.srcDirs  «  [] 

jniLibs.srcDir  “src/main/libs” 

} 

} 

f)  Create  an  “Android.mk”  makefile,  shown  in  Fig.  12,  under  the  “jni” 
directory  to  determine  how  to  build  the  C  code: 

i)  Select  “jni->New->File”. 

ii)  Enter  “Android.mk”  as  the  filename. 


D 

1  Hi 

i  0 

►  aPP  ►  #  ► :  R  y*  m  $  o 

•U'  ? 

Q 

~~g 

AddTwoNumbers  app  C]  src  C]  main  Ctjni  Android.mk 

3 

Ef 

1  Project  ▼  ,  ©  4=  #•  !*■ 

activity main.xml  x  c  MainActivity.java  x 

c  NativeLib.java  x  |  0  Android.mk  x  S'  app  x  k  com_example_haovu_addtwonumbers_NativeLibJt  x  | 

^=7 

m 

2 

▼ 

AddTwoNumbers  (~/Documents/N!yAndroidDev/Ad( 

LOCAL_PATH  :=  $(call  my-dir) 

V 

f 

u 

►  CH.gradle 

<$> 

►  tl.idea 

include  S(CLEAR_VARS) 

s 

▼  Caapp 

►  D  build 

LOCAL  MODULE  =  NativeLib  C| 
LOCAL_SRC_FILES  :=  NativeLib_C.c 

B 

CD  libs 

T 

Dsrc 

include  $ ( BUI LD_SHARED_LIBRARY ) 

0 

►  Cl  androidTest 

i 

V 

▼  Dmain 

n 

3 

►  C  java 

2 

▼  Djni 

M 

Android.mk 

V 

:■  com_example_haovu_addtwonumbe 
[«  Native Lib_C.c 
[■r  Native Lib_C.h 

►  fires 

H  Android  Manifest.xml 

►  Dtest 

0  .gitignore 

31  app.iml 

0  build.gradle 

0  proguard-rules.pro 

►  Dgradle 

0  .gitignore 

51  AddTwoNumbers.iml 

0  build.gradle 

01  gradle.  properties 

Messages  Cradle  Build 

L 

\u 

j 

:app:mergeDebugAndroidTestResources  UP-TO-DATE 

:app:processDebugAndroidTestResources  UP-TO-DATE 

2 

X 

“ 

:app:generateDebugAndroidTestSources  UP-TO-DATE 

o 

* 

£ 

:app:compileDebugJavaWitliJavac 

m 

:app:compileDebugNdk  UP-TO-DATE 

■Sil 

4 

:app:compileDebugSources 

1 1 

T 

:app:compileDebugAndroidTesijavaWithJavac 

? 

:app:compileDebugAndroidTestNdk  UP-TO-DATE 

.1 

|5 

:app:compileDebugAndroidTestSources 

Q  BUILD  SUCCESSFUL 

'W 

> 

cL 

> 

G  Total  time:  1.787  secs 

o 

O  0  errors 

2 

O  0  warnings 

G  See  complete  output  in  console 

£ 

HI  Terminal  >$<  6:  Android  Monitor  0:  Messages  ►  4:  Run  TODO 

T3  Event  Log  E  Cradle  Console 

□  Cradle  build  finished  in  Is  845ms  (today  11:20  AM) 

5:27  n 

a  UTF-8;  Context  <  no  contexts-  & 

Fig.  12  Android.mk  makefile 
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g)  Create  the  “Application.mk”  makefile,  shown  in  Fig.  13,  under  the 
“jni”  directory  to  tell  the  NDK  what  architecture  it  should  build  the 
shared  library  for: 

i)  Select  “jni->New->File”. 

ii)  Enter  “Application.mk”  as  the  filename. 


■rappel  ►  ►;  Git  p  §|  $  It  S  .«•  . 

Q 

AddTwoNumbers  app  E  src  E  main  E  ini 

g  Project  »  Q  4s  I* *"  *»  activity mainj<ml  x  c  MainActivity.java  x  c  NativeLib.java  x 

0  Androidunk  x  |  0  Application.mk  x  0  app  x  | 

»=2 

m 

2  ▼  E AddTwoNumbers  Documents/MyAndroidDev/Adi  APP_M0DULES  :=  NativeLib_C 

V 

5 

►  El  .grad le 

►  E  .idea 
▼  CEapp 

►  E  build 
E  libs 
▼  Esrc 

►  EandroidTest 
▼  Emain 

►  Ejava 

►  Ejni 

►  Cires 

■■  AndroidManifest.xml 

►  Etest 
0  .gitignore 
91  app.iml 

0  build. gradle 
0  proguard-rules.pro 

►  E  gradle 

0  .gitignore 
91  AddTwoNumbers.iml 
0  build. gradle 
01  gradle.  properties 
0  grad  lew 
0  gradlew.bat 
01  local. properties 
0  settings.gradle 
Messages  Cradle  Build 


APP_ABI  :=  all 


X  #= 

t  i 
+  B 

r- 


:app:mergeDebugAndroidTestResources  UP-TO-DATE 
:app:processDebugAndroidTestResources  UP-TO-DATE 
:app:generateDebugAndroidTestSources  UP-TO-DATE 
:app:compileDebugJavaWithJavac 
:app:compileDebugNdk  UP-TO-DATE 
:app:compileDebugSources 
:app:compileDebugAndroidTestlavaWithJavac 
:app:compileDebugAndroidTestNdk  UP-TO-DATE 
:app:compileDebugAndroidTestSources 
Q  BUILD  SUCCESSFUL 
Q  Total  time:  1.787  secs 
O  0  errors 
O  0  warnings 

O  See  complete  output  in  console 


[1  Terminal  >jj<  6:  Android  Monitor  0:  Messages  ^  4:  Run  ^  TODO 

Session  'app':  Launched  on  motorola-nexus_6-ZXlG22LFTP  (4/14/16, 3:59  PM) 


T3  Event  Log  E  Cradle  Console 
1:27  n/a  UTF-8J  Context:  <  no  context>  i 


Fig.  13  Application.mk  makefile 

Note:  This  application.mk  requests  the  NDK  to  build  a  shared  library  for  all 
supported  architectures.  The  following  details  how  to  build  a  shared  library: 

1)  Select  “app->NDK->ndk-build”: 

•  A  “libs”  directory  that  stores  the  shared  library  for  all  the  architectures 
is  automatically  created. 

•  All  the  supported  architecture  directories  are  created. 

•  Under  each  architecture  directory,  a  shared  library  for  that  particular 
architecture  can  be  found. 
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6.  Final  Build  and  Run  Android  Application 


Perform  the  following  steps  to  create  the  final  build  and  run  the  Android 
application: 

1)  Select  “Build->Make  Project”. 

2)  Select  “Run->  Run  ‘app”\ 

7.  Conclusion 


This  guide  summarizes  all  the  necessary  mechanisms  and  steps  to  guide  a  novice 
Android  application  developer  to  build  an  Android  application  that  is  capable  of 
handling  a  high-intensive  computation  requirement. 
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